From 9addcd0f764c76eff84273655481f6c55965a3ee Mon Sep 17 00:00:00 2001
From: "Karl O. Pinc" <kop@karlpinc.com>
Date: Thu, 26 Sep 2024 15:35:01 -0500
Subject: [PATCH] Present user with information about EOL normalization

---
 src/pgwui_sql/static/pgwui_sql.css   |  5 ++++
 src/pgwui_sql/static/sql_edit.js     | 13 ++++++++
 src/pgwui_sql/templates/sql_edit.mak | 45 ++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+)

diff --git a/src/pgwui_sql/static/pgwui_sql.css b/src/pgwui_sql/static/pgwui_sql.css
index 3594c6d..1524caf 100644
--- a/src/pgwui_sql/static/pgwui_sql.css
+++ b/src/pgwui_sql/static/pgwui_sql.css
@@ -65,3 +65,8 @@ textarea.sqltext { height: 40em;
                  bottom: 0;
                  background-color: white;  /* kludge, see above */
                  text-align: right; }
+
+/* The information on EOL normalization */
+tr.eol_info > td > span > p { cursor: pointer; }
+tr.eol_info > td > span > p + p { margin-left: 10%;
+                                  margin-right: 10%; }
diff --git a/src/pgwui_sql/static/sql_edit.js b/src/pgwui_sql/static/sql_edit.js
index 7bb0eab..0f2a353 100644
--- a/src/pgwui_sql/static/sql_edit.js
+++ b/src/pgwui_sql/static/sql_edit.js
@@ -45,3 +45,16 @@ function toggle_sql_used(elem) {
     sql_text.style.backgroundColor = '';
   }
 };
+
+function toggleEOLInfoRow() {
+    const collapsed = document.getElementById('collapsed_eol_info_id');
+    const expanded = document.getElementById('expanded_eol_info_id');
+    const collapsed_state = collapsed.getAttribute('hidden');
+    if (collapsed_state === null || collapsed_state === 'until-found') {
+        collapsed.setAttribute('hidden', 'hidden');
+        expanded.removeAttribute('hidden');
+    } else {
+        collapsed.removeAttribute('hidden');
+        expanded.setAttribute('hidden', 'hidden');
+    }
+}
diff --git a/src/pgwui_sql/templates/sql_edit.mak b/src/pgwui_sql/templates/sql_edit.mak
index 213e473..c3acad3 100644
--- a/src/pgwui_sql/templates/sql_edit.mak
+++ b/src/pgwui_sql/templates/sql_edit.mak
@@ -141,6 +141,50 @@
       </tr>
 </%def>
 
+<%def name="eol_info_row(tab_index)">
+      <tr class="eol_info">
+        <td colspan="4"><span id="collapsed_eol_info_id"
+          ><p onclick="toggleEOLInfoRow()" onkeydown="toggleEOLInfoRow()"
+              tabindex="${tab_index.val}"
+          >▲ Important information about end-of-line characters</p></span><span
+            id="expanded_eol_info_id" hidden><p
+            onclick="toggleEOLInfoRow()" onkeydown="toggleEOLInfoRow()"
+            tabindex="${tab_index.val}"
+          >▼ Important information about end-of-line-characters</p>
+          <p>The <a href="https://en.wikipedia.org/wiki/Newline">end-of-line
+             (EOL) character sequences</a> entered on this form
+             are normalized before the SQL is submitted for execution.
+             <em>This impacts how your SQL interacts with all multi-line
+             text stored in your databases.</em>
+             For example, SQL that inserts multi-line text into the
+             database will insert text that has normalized EOLs.</p>
+          <p>For full control over the the EOL sequences in the SQL submitted
+             to the database you must upload your SQL from a file.
+             EOL characters in uploaded SQL are not normalized.</p>
+          <p>The SQL displayed on the results page is always the normalized
+             form.
+             This matters if you copy-and-paste the displayed SQL.</p>
+          <p>The different EOL sequences of
+             linefeed, carriage return, and carriage return + line feed, are
+             all normalized to linefeed before submission to the server.
+             The normalization of EOL sequences to linefeeds, also known as
+             newlines, is consistent with the HTML standard.</p>
+          <p>Normalization is needed to ensure a consistent user experience.
+             The text entered in
+             <a href="https://html.spec.whatwg.org/multipage/form-elements.html#the-textarea-element">HTML
+             textarea elements</a>, as of 2024, is
+             supplied to the server with EOL sequences that vary by browser.
+             Further, around 2021 the
+             <a href="https://github.com/whatwg/html/issues/6647">standard
+             changed</a>.
+             Without normalization, interaction with the EOL character
+             sequences stored in the database would vary in ways
+             difficult to predict.</p></span>
+        </td>
+      </tr>
+      <% tab_index.inc() %>
+</%def>
+
 <%def name="download_row(tab_index)">
       <tr>
         ## Download
@@ -243,6 +287,7 @@
 <%def name="controls(tab_index)">
   <table>
     ${self.file_input_row(tab_index)}
+    ${self.eol_info_row(tab_index)}
     ${self.null_rep_row(tab_index)}
     ${self.download_row(tab_index)}
     ${self.download_as_row(tab_index)}
-- 
2.34.1